---
title: ストリーミング
description: Stream agent output in real time using the Runner
---

import { Code } from '@astrojs/starlight/components';
import basicStreamingExample from '../../../../../../examples/docs/streaming/basicStreaming.ts?raw';
import nodeTextStreamExample from '../../../../../../examples/docs/streaming/nodeTextStream.ts?raw';
import handleAllEventsExample from '../../../../../../examples/docs/streaming/handleAllEvents.ts?raw';
import streamedHITLExample from '../../../../../../examples/docs/streaming/streamedHITL.ts?raw';

Agents SDK は、モデルやその他の実行ステップからの出力を段階的に配信できます。ストリーミングにより UI を応答性よく保ち、エージェントの最終的な実行結果全体を待たずに ユーザー を更新できます。

## ストリーミングの有効化

`Runner.run()` に `{ stream: true }` オプションを渡すと、完全な結果ではなくストリーミングオブジェクトを取得します:

<Code
  lang="typescript"
  code={basicStreamingExample}
  title="ストリーミングを有効化"
/>

ストリーミングが有効な場合、返される `stream` は `AsyncIterable` インターフェースを実装します。各イベントは、その実行内で何が起こったかを表すオブジェクトです。ストリームは 3 種類のイベントを出力し、それぞれがエージェントの実行の異なる部分を表します。多くのアプリケーションはモデルのテキストだけが必要なので、ストリームはそのためのヘルパーを提供します。

### テキスト出力の取得

`stream.toTextStream()` を呼び出すと、生成されたテキストのストリームを取得できます。`compatibleWithNodeStreams` が `true` の場合、戻り値は通常の Node.js の `Readable` です。`process.stdout` や別の出力先にそのままパイプできます。

<Code
  lang="typescript"
  code={nodeTextStreamExample}
  title="到着したテキストを逐次ログ出力"
  meta={`{13-17}`}
/>

`stream.completed` の Promise は、実行と保留中のすべてのコールバックが完了すると解決されます。出力がもうないことを確実にするには、必ず待機してください。

### すべてのイベントを監視

`for await` ループを使って、到着した各イベントを検査できます。有用な情報には、低レベルのモデルイベント、エージェントの切り替え、SDK 固有の実行情報などがあります:

<Code
  lang="typescript"
  code={handleAllEventsExample}
  title="すべてのイベントを監視"
/>

完全なプレーンテキストストリームと 元 のイベントストリームをどちらも出力するスクリプトは、[the streamed example](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/streamed.ts) を参照してください。

## イベントタイプ

ストリームは 3 種類のイベントを出力します:

### raw_model_stream_event

```ts
type RunRawModelStreamEvent = {
  type: 'raw_model_stream_event';
  data: ResponseStreamEvent;
};
```

例:

```json
{
  "type": "raw_model_stream_event",
  "data": {
    "type": "output_text_delta",
    "delta": "Hello"
  }
}
```

### run_item_stream_event

```ts
type RunItemStreamEvent = {
  type: 'run_item_stream_event';
  name: RunItemStreamEventName;
  item: RunItem;
};
```

ハンドオフのペイロード例:

```json
{
  "type": "run_item_stream_event",
  "name": "handoff_occurred",
  "item": {
    "type": "handoff_call",
    "id": "h1",
    "status": "completed",
    "name": "transfer_to_refund_agent"
  }
}
```

### agent_updated_stream_event

```ts
type RunAgentUpdatedStreamEvent = {
  type: 'agent_updated_stream_event';
  agent: Agent<any, any>;
};
```

例:

```json
{
  "type": "agent_updated_stream_event",
  "agent": {
    "name": "Refund Agent"
  }
}
```

## ストリーミング中の Human in the loop (人間の介入)

ストリーミングは、実行を一時停止するハンドオフ（たとえばツールに承認が必要な場合）と両立します。ストリームオブジェクトの `interruption` フィールドで中断を取得でき、各中断に対して `state.approve()` または `state.reject()` を呼び出すことで実行を継続できます。`{ stream: true }` で再実行すると、ストリーミング出力が再開します。

<Code
  lang="typescript"
  code={streamedHITLExample}
  title="ストリーミング中の人間による承認を処理"
/>

ユーザー と対話する、より完全なサンプルは
[`human-in-the-loop-stream.ts`](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/human-in-the-loop-stream.ts) です。

## ヒント

- すべての出力がフラッシュされることを保証するため、終了前に `stream.completed` を待つことを忘れないでください
- 最初の `{ stream: true }` オプションは、指定したその呼び出しにのみ適用されます。`RunState` で再実行する場合は、再度オプションを指定する必要があります
- アプリケーションがテキスト結果のみに関心がある場合は、個々のイベントオブジェクトを扱わなくて済むように `toTextStream()` を優先してください

ストリーミングとイベントシステムを使うことで、エージェントをチャットインターフェース、ターミナルアプリケーション、または ユーザー が段階的な更新から恩恵を受けるあらゆる場所に統合できます。
